<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Java Service Wrapper - wrapper.use_system_time Property</title>
<style media="all" type="text/css">
            @import url("./style/wrapper.css");
        </style>
</head>
<body bgcolor="#eeeeff" marginheight="0" marginwidth="0" leftmargin="0" topmargin="0" alink="#023264" vlink="#023264" link="#525D76" text="#000000">
<map name="wrapperLogo">
<area href="http://wrapper.tanukisoftware.org" coords="90,90,88" shape="circle">
</map>
<map name="wrapperTitle">
<area href="http://www.tanukisoftware.com" coords="28,32,176,48" shape="rect">
</map>
<table cellpadding="0" cellspacing="0" width="100%" border="0">
<tr>
<td valign="top" width="180">
<table cellpadding="0" cellspacing="0" width="100%" border="0">
<tr>
<td width="180"><img usemap="#wrapperLogo" border="0" height="180" width="180" src="images/WrapperLogo.png"></td>
</tr>
<tr>
<td>
<table cellpadding="4" cellspacing="0" width="100%" border="0">
<tr>
<td nowrap="true">
<div id="menu">
<script language="JavaScript">//@@MENU_TOP@@</script>
<div>
<b>Essentials</b>
<div>
<a href="introduction.html">Introduction</a>
</div>
<div>
<a href="integrate.html">Integration Methods</a>
</div>
<div>
<a href="properties.html">Configuration Properties</a>
</div>
<div>
<a href="launch.html">Launching Your Application</a>
</div>
<div>
<b>
                        &gt;&gt;
                        <a href="donate.html">Show Your Support</a>
                        &lt;&lt;
                    </b>
</div>
<div>
<a href="sponsors.html">Sponsors</a>
</div>
</div>
<div>
<b>Documentation</b>
<div>
<a href="jmx.html">JMX Control</a>
</div>
<div>
<a href="security-model.html">Security Model</a>
</div>
<div>
<a href="example.html">Feature Examples</a>
</div>
<div>
<a href="debugging.html">Debugging Your Application</a>
</div>
<div>
<a href="troubleshooting.html">Troubleshooting</a>
</div>
<div>
<a href="faq.html">FAQ</a>
</div>
<div>
<a href="release-notes.html">Release Notes</a>
</div>
<div>
<a href="history.html">Project History</a>
</div>
<div>
<a href="javadocs.html">Javadocs API</a>
</div>
<div>
<a href="buttons.html">Buttons</a>
</div>
<div>
<a href="authors.html">Authors</a>
</div>
<div>
<a href="license.html">License</a>
</div>
</div>
<div>
<b>Download</b>
<div>
<a href="http://sourceforge.net/project/showfiles.php?group_id=39428&package_id=31591">Binaries</a>
</div>
<div>
<a href="http://sourceforge.net/project/showfiles.php?group_id=39428&package_id=33658">Source Code</a>
</div>
</div>
<div>
<b>Get Involved</b>
<div>
<a href="http://sourceforge.net/projects/wrapper/">Source Forge</a>
</div>
<div>
<a href="http://svn.sourceforge.net/viewvc/wrapper/">Subversion Repository</a>
</div>
<div>
<a href="http://sourceforge.net/tracker/?group_id=39428">Issue Tracking</a>
</div>
<div>
<a href="http://sourceforge.net/mail/?group_id=39428">Mailing Lists and Archives</a>
</div>
<div>
<a href="http://sourceforge.net/forum/?group_id=39428">Forums (Old)</a>
</div>
</div>
</div>
<script language="JavaScript">//@@MENU_BOTTOM@@</script>
<p>
<b>Hosted by:</b>
<br>
<a href="http://sourceforge.net/projects/wrapper/"><img alt="SourceForge" border="0" height="31" width="88" src="http://sourceforge.net/sflogo.php?group_id=39428"></a>
<br>
</p>
</td>
</tr>
</table>
</td>
</tr>
</table>
</td><td valign="top" width="*">
<table cellpadding="0" cellspacing="0" width="100%" border="0">
<tr>
<td colspan="3"><img height="4" src="images/spacer.gif"></td>
</tr>
<tr>
<td align="center" height="90" colspan="2"><a href="http://wrapper.tanukisoftware.org"><img border="0" height="90" width="728" src="images/OfflineAd728x90.png"></a></td><td rowspan="5"><img width="4" src="images/spacer.gif"></td>
</tr>
<tr>
<td height="49" width="435"><img usemap="#wrapperTitle" border="0" height="49" width="435" src="images/WrapperTitle.png"></td><td valign="bottom" align="right" width="*"><a href="donate.html"><img border="0" height="16" width="300" src="images/DonationRequest.png"></a></td>
</tr>
<tr>
<td height="4" colspan="2"><img height="4" width="500" src="images/BorderTop.png"></td>
</tr>
<tr>
<td colspan="2">
<table cellspacing="0" cellpadding="0" width="100%" border="0">
<tr>
<td valign="top" width="4"><img height="496" width="4" src="images/BorderLeft.png"></td><td bgcolor="#ffffff" valign="top" width="*" colspan="2">
<table cellpadding="4" cellspacing="0" width="100%" border="0">
<tr>
<td nowrap="true" align="center"><font zcolor="#115b77" color="#8888aa" size="5"><b>wrapper.use_system_time Property</b></font></td>
</tr>
<tr>
<td>
<title>wrapper.use_system_time Property</title>
    
    
<a name="N10009"></a>
<table cellpadding="2" cellspacing="0" width="100%" border="0">
<tr>
<td bgcolor="#8888aa" class="sectionheader1" width="*"><font color="#eeeeee" size="4"><b>Configuration Property Overview</b></font></td>
</tr>
<tr>
<td><img height="4" width="1" src="./images/spacer.gif"></td>
</tr>
<tr>
<td>
        
        
<ul>
            
<li>
                
<a href="properties.html">Configuration Property Overview</a>
            
</li>
            
<li>
                
<a href="props-advanced.html">Advanced Properties</a>
            
</li>
            
<li>
                
<a href="properties.html#name">Property List by Name</a>
            
</li>
        
</ul>
    
</td>
</tr>
</table>
    
<a name="N10027"></a>
<table cellpadding="2" cellspacing="0" width="100%" border="0">
<tr>
<td bgcolor="#8888aa" class="sectionheader1" width="*"><font color="#eeeeee" size="4"><b>wrapper.use_system_time</b></font></td>
</tr>
<tr>
<td><img height="4" width="1" src="./images/spacer.gif"></td>
</tr>
<tr>
<td>
        
        
<p>
            Controls how the Wrapper internally manages the passage of time
            and scheduling of events.  If <a href="#use-true">true</a>
            then the Wrapper will make use of the system time for all internal
            timekeeping functions.  Setting it to <a href="#use-false">false</a>
            will cause the Wrapper to make use of a background timer thread
            which keeps time by incrementing a "tick" counter.  Defaults to false.
        </p>
        
<table cellspacing="0" cellpadding="0" width="100%" border="0" class="listing">
<tr>
<td class="listingcaption"><i>Example:</i></td>
</tr>
<tr>
<td bgcolor="#eeeeee" class="listingcell"><font color="#444444">
<pre class="listingpre">wrapper.use_system_time=FALSE</pre>
</font></td>
</tr>
</table>
        
<p>
            Each value of this property has advantages in certain situations.
        </p>
        
<div class="note">
<table cellspacing="0" cellpadding="2" width="100%" border="0">
<tr>
<td nowrap="nowrap" valign="top">
<p class="notelabel">
<font color="#0000a0"><b>NOTE MEG</b></font>
</p>
</td><td><img width="10" src="images/spacer.gif"></td><td bgcolor="#bbbbdd" class="notebody"><font color="#222260">
            
<p>
                
<a href="prop-restart-reload-configuration.html">Reloading</a>
                the Wrapper configuration will have no effect on the value of this property.
                Changes will not take effect until the Wrapper has been restarted.  The threshold
                properties described below can be updated.
            </p>
        
</font></td>
</tr>
</table>
</div>
        
<a name="use-true"></a>
<table cellpadding="2" cellspacing="0" width="100%" border="0">
<tr>
<td rowspan="3" width="10"><img height="1" width="10" src="./images/spacer.gif"></td><td bgcolor="#9999bb" class="sectionheader2" width="*"><font color="#eeeeee" size="3"><b>wrapper.use_system_time=true (System time)</b></font></td>
</tr>
<tr>
<td><img height="4" width="1" src="./images/spacer.gif"></td>
</tr>
<tr>
<td>
            
            
<p>
                Historically, the Wrapper has always used the system time for internal
                timekeeping.  In the majority of cases this works perfectly.  However
                there are a few cases where this will fail or the Wrapper does not do
                what may be expected:
            </p>
            
<ul>
                
<li>
                    
<p>
                        If the Wrapper is in a situation where it is competing for CPU with
                        other processes that are operating at a higher priority, it is
                        possible that the Wrapper and/or its JVM will not get any CPU cycles
                        for long periods of time.  The Wrapper has always handled these
                        cases by using logic that detects such situations and extends
                        any affected timeouts appropriately.  In rare cases however, the
                        Wrapper will falsely think that the JVM has become frozen and
                        restart it.
                    </p>
                
</li>
                
<li>
                    
<p>
                        System time changes.  If the system time is set forward or backward
                        by more than a few seconds while the Wrapper is running, one or more
                        of its timeouts could be triggered, resulting in an unintended JVM
                        restart.  In most cases, the Wrapper will handle time changes as
                        if the process had been starved of CPU.  But there are cases were
                        this will fail.
                    </p>
                    
<p>
                        In general, setting the clock forward works correctly.  A message will
                        be displayed in the console notifying the user that the Wrapper did
                        not receive any CPU for x seconds.  But the Wrapper will continue to
                        function correctly.
                    </p>
                    
<p>
                        Setting the system time backwards however can cause a number of
                        problems depending on exactly what state the Wrapper is in when
                        it happens.  Internally, the Wrapper schedules events at specific
                        future points in time when operations like pinging, or launching
                        a new JVM should take place.   If the time is set back by an hour
                        then an operation that was scheduled to take place after 5 seconds
                        will not happen for an hour and 5 seconds.  If the timing of this
                        is perfect then the Wrapper may stop pinging the JVM and the JVM
                        will respond to a lack of pings by initiating a JVM restart.
                    </p>
                    
<div class="note">
<table cellspacing="0" cellpadding="2" width="100%" border="0">
<tr>
<td nowrap="nowrap" valign="top">
<p class="notelabel">
<font color="#0000a0"><b>NOTE MEG</b></font>
</p>
</td><td><img width="10" src="images/spacer.gif"></td><td bgcolor="#bbbbdd" class="notebody"><font color="#222260">
                        
<p>Day light savings time</p>
                        
<p>
                            The Wrapper will not work correctly during day light savings
                            time.  If you live in a country which likes to change the time
                            every spring and fall then it is recommended that you use the
                            tick timer to avoid timeouts.
                        </p>
                        
<p>
                            As described above, you may get a single JVM restart either in
                            the spring or fall as the system time is adjusted.  Once the
                            JVM has been restarted however your application should continue
                            to function correctly.
                        </p>
                    
</font></td>
</tr>
</table>
</div>
                
</li>
                
<li>
                    
<p>
                        System suspend and resume.  If the Wrapper is being used on a system
                        that can be suspended to disk or ram for long periods of time, the
                        system time will appear to have jumped forward when the machine is
                        resumed.  Other than a console message, this works correctly.
                    </p>
                
</li>
            
</ul>
        
</td>
</tr>
</table>
        
<a name="use-false"></a>
<table cellpadding="2" cellspacing="0" width="100%" border="0">
<tr>
<td rowspan="3" width="10"><img height="1" width="10" src="./images/spacer.gif"></td><td bgcolor="#9999bb" class="sectionheader2" width="*"><font color="#eeeeee" size="3"><b>wrapper.use_system_time=false (Timer thread)</b></font></td>
</tr>
<tr>
<td><img height="4" width="1" src="./images/spacer.gif"></td>
</tr>
<tr>
<td>
            
            
<p>
                As of version 3.1.0, a new timer mechanism was added to the Wrapper.
                This new timer was made the default in version 3.2.0.
                Rather than keeping time by querying the system clock, the Wrapper
                creates a background thread which enters a light weight loop and
                increments an internal "tick" counter.  Internally all timekeeping
                has been modified to be based on these "ticks".  (If the system time
                is being used then the tick count at any particular moment is
                calculated from the system time rather than from the counter.)
            </p>
            
<p>
                This has turned out to have a number of advantages:
            </p>
            
<ul>
                
<li>
                    
<p>
                        The Wrapper is no longer affected by changes to the system
                        time, either forward or backwards.  This guarantees that the
                        Wrapper will behave correctly when the time is adjusted for
                        day light savings time or other adjustments.
                    </p>
                
</li>
                
<li>
                    
<p>
                        When a suspended system is resumed, the Wrapper continues
                        on where it left off without any problems.
                    </p>
                
</li>
                
<li>
                    
<p>
                        The Wrapper handles cases where it is running in a CPU
                        starved state reliably because the tick count is incremented
                        at a rate that reflects the amount of CPU being received,
                        rather than being absolute.  This means that timeouts due
                        to high loads are very unlikely.
                    </p>
                    
<p>
                        In extreme cases, if the Wrapper receives some CPU but the
                        JVM is completely starved, or vica versa, timeouts will
                        still be possible.  The two processes always operate at
                        the exact same priority, however, so this is very unlikely.
                    </p>
                
</li>
            
</ul>
            
<p>
                There are, however, some disadvantages to using a "tick" counter for
                timekeeping:
            </p>
            
<ul>
                
<li>
                    
<p>
                        The tick timer requires that an additional thread be allocated
                        within the native Wrapper.  This results in a slight increase
                        in the resources needed to run the Wrapper.
                    </p>
                    
<p>
                        The Java side of the Wrapper makes use of a thread that was
                        already being used to check for system signals so there is
                        no increase in resources on the Java side.
                    </p>
                
</li>
                
<li>
                    
<p>
                        At anything less than 100% CPU load, the timer threads will
                        always get just enough CPU to increment their counts and be
                        temporally accurate.  But when the system is running at 100%
                        CPU, the thread will not be able to loop at full speed
                        resulting in the count being incremented more slowly.  In
                        most cases, this is actually a good thing.  However it will
                        cause operations like the ping interval to be inconsistent
                        at times, so must be kept in mind.
                    </p>
                
</li>
            
</ul>
        
</td>
</tr>
</table>
        
<a name="N100BA"></a>
<table cellpadding="2" cellspacing="0" width="100%" border="0">
<tr>
<td rowspan="3" width="10"><img height="1" width="10" src="./images/spacer.gif"></td><td bgcolor="#9999bb" class="sectionheader2" width="*"><font color="#eeeeee" size="3"><b>Timer Debug properties</b></font></td>
</tr>
<tr>
<td><img height="4" width="1" src="./images/spacer.gif"></td>
</tr>
<tr>
<td>
            
            
<p>
                The wrapper also implements a pair of properties that are useful
                for monitoring when either the JVM or Wrapper timer threads gain
                or lose time relative to the system clock.  They were mainly
                implemented for debugging purposes, but can provide very useful
                information about the state of the system.  They are described
                here rather than on their own page as they have no meaning outside
                this context.
            </p>
            
<a name="prop-timer-slow-threshold"></a>
<table cellpadding="2" cellspacing="0" width="100%" border="0">
<tr>
<td rowspan="3" width="10"><img height="1" width="10" src="./images/spacer.gif"></td><td bgcolor="#aaaacc" class="sectionheader3" width="*"><font color="#eeeeee" size="2"><b>wrapper.timer_slow_threshold</b></font></td>
</tr>
<tr>
<td><img height="4" width="1" src="./images/spacer.gif"></td>
</tr>
<tr>
<td>
                
                
<p>
                    The wrapper.timer_slow_threshold
                    property will display a message to the log whenever the "tick"
                    timer falls behind the system time by more than a threshold
                    number of seconds, within a single loop of the timer thread.
                    The default value of this property is very high to effectively
                    disable it.
                </p>
                
<table cellspacing="0" cellpadding="0" width="100%" border="0" class="listing">
<tr>
<td class="listingcaption"><i>Example:</i></td>
</tr>
<tr>
<td bgcolor="#eeeeee" class="listingcell"><font color="#444444">
<pre class="listingpre">wrapper.timer_slow_threshold=10</pre>
</font></td>
</tr>
</table>
                
<p>
                    Setting the slow threshold to a low value like 1 second will
                    provide useful information about when during the day the system
                    is under load.
                </p>
                
<p>
                    A value of 0 will show every single slip in time and is in
                    general not very useful.  Even under very light load, the
                    timer will fall slightly behind the system clock simply
                    because the loop itself takes a finite amount of time to
                    complete.
                </p>
                
<p>
                    Slightly higher values like 10 seconds can actually be quite
                    useful as they will point out any major periods of high load
                    on the system, while not bothering to log every single CPU
                    hiccup.
                </p>
                
<p>
                    Any forward adjustments in the system clock will be
                    interpreted as a period of high CPU load that lasted the
                    duration that the clock was advanced.
                </p>
                
<p>
                    If for example you have set this property to a low value and the
                    system clock is either set ahead by one minute, or is under extremely
                    heavy load for a minute, you will see output in your logs like the
                    following:
                </p>
                
<table cellspacing="0" cellpadding="0" width="100%" border="0" class="listing">
<tr>
<td class="listingcaption"><i>Example:</i></td>
</tr>
<tr>
<td bgcolor="#eeeeee" class="listingcell"><font color="#444444">
<pre class="listingpre">INFO   | wrapper  | 2004/07/21 08:52:01 | The timer fell behind the system clock by 60000ms.
INFO   | jvm 1    | 2004/07/21 08:52:15 | The timer fell behind the system clock by 60000ms.</pre>
</font></td>
</tr>
</table>
                
<p>
                    The pair of messages indicates that both the wrapper and JVM
                    processes noticed the change in system time.  It is quite common
                    for the numbers reported by the two processes to differ slightly
                    when the just is caused by heavy load.
                </p>
            
</td>
</tr>
</table>
            
<a name="prop-timer-fast-threshold"></a>
<table cellpadding="2" cellspacing="0" width="100%" border="0">
<tr>
<td rowspan="3" width="10"><img height="1" width="10" src="./images/spacer.gif"></td><td bgcolor="#aaaacc" class="sectionheader3" width="*"><font color="#eeeeee" size="2"><b>wrapper.timer_fast_threshold</b></font></td>
</tr>
<tr>
<td><img height="4" width="1" src="./images/spacer.gif"></td>
</tr>
<tr>
<td>
                
                
<p>
                    The wrapper.timer_fast_threshold
                    property will display a message to the log whenever the system
                    time falls behind the "tick" timer by more than a threshold
                    number of seconds within, a single loop of the timer thread.
                    The default value of this property is very high to effectively
                    disable it.
                </p>
                
<table cellspacing="0" cellpadding="0" width="100%" border="0" class="listing">
<tr>
<td class="listingcaption"><i>Example:</i></td>
</tr>
<tr>
<td bgcolor="#eeeeee" class="listingcell"><font color="#444444">
<pre class="listingpre">wrapper.timer_fast_threshold=0</pre>
</font></td>
</tr>
</table>
                
<p>
                    Setting the fast threshold to a low value is not generally as
                    useful as the slow threshold property above.  Under normal
                    operation, the "tick" timer will never advance beyond the
                    system time.  The only exception is in the case where the
                    system clock has been set back.  Setting the property to
                    0 will detect any such backward adjustments of the system
                    clock.
                </p>
                
<p>
                    If for example you have set this property to a low value and the
                    system clock is set back by one minute, you will see output in
                    your logs like the following:
                </p>
                
<table cellspacing="0" cellpadding="0" width="100%" border="0" class="listing">
<tr>
<td class="listingcaption"><i>Example:</i></td>
</tr>
<tr>
<td bgcolor="#eeeeee" class="listingcell"><font color="#444444">
<pre class="listingpre">INFO   | wrapper  | 2004/07/21 08:52:01 | The system clock fell behind the timer by 60000ms.
INFO   | jvm 1    | 2004/07/21 08:52:15 | The system clock fell behind the timer by 60000ms.</pre>
</font></td>
</tr>
</table>
                
<p>
                    The pair of messages indicates that both the wrapper and JVM
                    processes noticed the change in system time.
                </p>
            
</td>
</tr>
</table>
        
</td>
</tr>
</table>
    
</td>
</tr>
</table>

</td>
</tr>
<tr>
<td align="right" id="author">
<p>
<i>by Leif Mortenson</i>
</p>
</td>
</tr>
</table>
<script language="JavaScript">//@@BODY_SECTION@@</script></td><td valign="bottom" width="4"><img height="496" width="4" src="images/BorderRight.png"></td>
</tr>
</table>
</td>
</tr>
<tr>
<td align="right" height="4" colspan="2"><img height="4" width="500" src="images/BorderBottom.png"></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellpadding="2" cellspacing="0" border="0" width="100%">
<tr>
<td id="copyright" align="left"><font color="#525D76" size="-1" face="arial,helvetica,sanserif"><i>
                            Copyright &copy;1999-2004 by <a href="http://www.tanukisoftware.com">Tanuki Software</a>.
                            All Rights Reserved.
                        </i></font></td><td align="right"><font color="#525D76" size="-1" face="arial,helvetica,sanserif"><i>
                            last modified:
                            <script language="JavaScript"> document.write(document.lastModified); </script></i></font></td>
</tr>
</table>
</body>
</html>
